home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 2: CDPD 1 / Almathera Ten on Ten - Disc 2: CDPD 1.iso / pd / 351-375 / 354 / mxmlib / libinfo.prf < prev    next >
Text File  |  1995-03-14  |  24KB  |  853 lines
  1. .define function
  2. .lm 0
  3. .ce 0
  4. .bp 1
  5. .he |mxm.library/$1||mxm.library/$1|
  6. .fi
  7. .ju
  8. .en
  9.  
  10. .define note
  11. .sp
  12. .lm 3
  13. $1 $2
  14. .lm 7
  15. .en
  16.  
  17. .define put
  18. .sp
  19. $1 $2 $3 $4 $5 $6 $7
  20. .lm 7
  21. .en
  22.  
  23. .define info
  24. .lm 7
  25. $1 -
  26. .lm 11
  27. .en
  28.  
  29. .define see
  30. .sp
  31. .lm 3
  32. SEE ALSO
  33. .lm 7
  34. .nj
  35. $1 $2 $3 $4 $5 $6 $7 $8 $9
  36. .ju
  37. .en
  38.  
  39. .define synopsis
  40. .sp
  41. .lm 3
  42. SYNOPSIS
  43. .lm 7
  44. .nj
  45. $1 $2 $3 $4 $5 $6 $7 $8 $9
  46. .ju
  47. .en
  48.  
  49. .function PURPOSE
  50. .note BACKGROUND
  51. mxm.library was created to support our in-house development
  52. environment. It contains basic support functions as well as routines
  53. frequently used but never to be found in any library. It seems strange
  54. that most functions to be found in mxm.library will be included in
  55. Kickstart 1.4. The contents of the library were put together from
  56. various sources. You will find code derived from 'ancient' Developers'
  57. kit sources, sample routines suggested on older public-domain disks as
  58. well as new routines written by us. Many different areas of
  59. programming are covered by mxm.library routines. Some routines check
  60. gadgets while other deal with data encryption or produce sounds. All
  61. in all we have tried to keep the library as small as possible and -
  62. most important - reentrant.
  63. .note CREDITS
  64. The ikm.c source code was developed by Jimm Mackraz of
  65. Commodore-Amiga, Inc., Los Gatos.  AllocRem/FreeRem were created from
  66. old EA IFF sources.  PopMenu was extended from example source code by
  67. Gambit Software.  The Crc-16-bit checksumming routines were created by
  68. Stephen Satchell and Chuck Forsberg.
  69. .note CONTRIBUTIONS
  70. If you are interested in adding new functions to mxm.library mail them
  71. to us on disk. They will be included in the next library release.
  72. .note ADDRESS
  73. Olaf Barthel, MXM
  74. .put Brabeckstrasse 35
  75. .put D-3000 Hannover 71
  76. .put Federal Republic of Germany
  77. .function AllocRem
  78. .note NAME
  79. AllocRem - Allocate a chunk of memory
  80. .synopsis MemoryBlock = AllocRem(Size,Requirements)
  81. .note FUNCTION
  82. Very similar to AllocMem, AllocRem allocates a chunk of memory, according to
  83. size and type passed in arguments. The only difference is that the
  84. size of the memory block being allocated is remembered.
  85. .note INPUTS
  86. .info Size
  87. The number of bytes to allocate.
  88. .info Requirements
  89. Flags such as MEMF__CHIP, MEMF__FAST, MEMF__PUBLIC, MEMF__CLEAR.
  90. .note RESULTS
  91. .info MemoryBlock
  92. A pointer to the allocated chunk of memory or NULL.
  93. .note BUGS
  94. .see exec.library/AllocMem, exec.library/FreeMem, mxm.library/AllocRem
  95.  
  96. .function FreeRem
  97. .note NAME
  98. FreeRem - Free a chunk of memory
  99. .synopsis Pointer = FreeRem(MemoryBlock)
  100. .note FUNCTION
  101. FreeRem deallocates a block of memory previously allocated by
  102. AllocRem. The size of the block does not need to specified since it is
  103. stored in the first longword of the MemoryBlock. This function is
  104. quite safe since NULL pointers are skipped.
  105. .note INPUTS
  106. .info MemoryBlock
  107. Pointer to the chunk of memory to be allocated.
  108. .note RESULTS
  109. .info Pointer
  110. This function always returns NULL, so user can do Pointer =
  111. FreeRem(Pointer).
  112. .note BUGS
  113. FreeRem cannot be used to deallocate memory allocated via AllocMem.
  114. .see exec.library/AllocMem, exec.library/FreeMem, mxm.library/FreeRem
  115.  
  116. .function CreateFuncTask
  117. .note NAME
  118. CreateFuncTask - Create a task
  119. .synopsis Task = CreateFuncTask(TaskName,Priority,InitialPC,StackSize)
  120. .note FUNCTION
  121. CreateFuncTask creates a task from a given function and adds it to the
  122. system list. The name of the task to be created does not need to be
  123. statically initialized. It is copied into a separate chunk of memory
  124. and gets freed by DeleteFuncTask().
  125. .note INPUTS
  126. .info TaskName
  127. Pointer to null-terminated string.
  128. .info Priority
  129. The priority the task will be started from.
  130. .info InitialPC
  131. Pointer to function to be started as a task.
  132. .info StackSize
  133. The stack size you wish to execute the task with.
  134. .note RESULTS
  135. .info Task
  136. Pointer to a Task-structure, or NULL.
  137. .note BUGS
  138. .see exec.library/AddTask
  139.  
  140. .function DeleteFuncTask
  141. .note NAME
  142. DeleteFuncTask - Delete a task
  143. .synopsis Pointer = DeleteFuncTask(Task)
  144. .note FUNCTION
  145. DeleteFuncTask removes a Task from the system list previously created
  146. with CreateFuncTask.
  147. .note INPUTS
  148. .info Task
  149. Pointer to a Task-structure.
  150. .note RESULTS
  151. This function always returns NULL, so user can do Pointer =
  152. DeleteFuncTask(Pointer).
  153. .note BUGS
  154. This function does not handle self-deletion properly.
  155. .see mxm.library/CreateFuncTask
  156.  
  157. .function CreateFuncProc
  158. .note NAME
  159. CreateFuncProc - Create a process
  160. .synopsis Proc = CreateFuncProc(ProcName,Priority,InitialPC,StackSize)
  161. .note FUNCTION
  162. CreateFuncProc creates a process from a given function and adds it to the
  163. system list.
  164. .note INPUTS
  165. .info ProcName
  166. Pointer to null-terminated string.
  167. .info Priority
  168. The priority the process will be started from.
  169. .info InitialPC
  170. Pointer to function to be started as a process.
  171. .info StackSize
  172. The stack size you wish to execute the process with.
  173. .note RESULTS
  174. .info Proc
  175. Pointer to a Process-structure, or NULL.
  176. .note BUGS
  177. Currently this function can only be called from processes, since
  178. DOS-routines are employed to install the new process.
  179. .see exec.library/AddTask, mxm.library/CreateFuncTask
  180.  
  181. .function MovePointer
  182. .note NAME
  183. MovePointer - Move the mouse pointer to given position
  184. .synopsis Success = MovePointer(Screen,Button,X,Y)
  185. .note FUNCTION
  186. MovePointer positions the mouse pointer at the given x/y position
  187. relative to the top/leftedge of a screen. Optionally a mouse-click can
  188. be simulated.
  189. .note INPUTS
  190. .info Screen
  191. Pointer to a Screen-structure.
  192. .info Button
  193. Boolean, TRUE if you want a mouse-click to be simulated, FALSE if not.
  194. .info X
  195. New X-position for the mouse pointer.
  196. .info Y
  197. New Y-position for the mouse pointer.
  198. .note RESULTS
  199. .info Success
  200. Boolean.
  201. .note BUGS
  202. .see
  203.  
  204. .function WriteConsole
  205. .note NAME
  206. WriteConsole - Write a string to a window.
  207. .synopsis Success = WriteConsole(Window,String)
  208. .note FUNCTION
  209. This function behaves very much like a call to the ANSI-function
  210. puts().  A string, which may include ANSI control codes, is printed
  211. into a window.
  212. .note INPUTS
  213. .info Window
  214. Pointer to a Window-structure.
  215. .info String
  216. Pointer to a null-terminated string.
  217. .note RESULTS
  218. .info Success
  219. Boolean.
  220. .note BUGS
  221. .see ANSI puts() command
  222.  
  223. .function DeletePrinterSupport
  224. .note NAME
  225. DeletePrinterSupport - Deallocate a PrinterSupport request.
  226. .synopsis Pointer = DeletePrinterSupport(Support)
  227. .note FUNCTION
  228. All necessary cleanups for the PrinterSupport functions are provided
  229. with this function (allocated memory is freed, device actions stopped
  230. and device driver is closed).
  231. .note INPUTS
  232. .info Support
  233. Pointer to a PrinterSupport-structure.
  234. .note RESULTS
  235. This function always returns NULL, so user can do Pointer =
  236. DeletePrinterSupport(Pointer).
  237. .note BUGS
  238. .see mxm.library/CreatePrinterSupport, mxm.library/StartPrinterDump,
  239. mxm.library/StopPrinterDump
  240.  
  241. .function CreatePrinterSupport
  242. .note NAME
  243. CreatePrinterSupport - Allocate a PrinterSupport-structure and
  244. prepare the unit driver for printing.
  245. .synopsis Support = CreatePrinterSupport(RastPort,ViewPort,LeftEdge,TopEdge,Width,Height,Large)
  246. .note FUNCTION
  247. This function creates a Dump-Rastport request for the printer.device
  248. and passes it back to the caller who has to start the dump by a call
  249. to StartPrinterDump().
  250. .note INPUTS
  251. .info RastPort
  252. Pointer to a RastPort-structure, area to be printed.
  253. .info ViewPort
  254. Pointer to a ViewPort-structure.
  255. .info LeftEdge/TopEdge
  256. Corner of area to start printing from.
  257. .info Width/Height
  258. Size of area to be printed.
  259. .info Large
  260. Set this to TRUE if you wish to have the area printed as large as
  261. possible.
  262. .note RESULTS
  263. Support = Pointer to a PrinterSupport-structure, or NULL.
  264. .note BUGS
  265. .see printer.device/PRD_DUMPRPORT
  266.  
  267. .function StartPrinterDump
  268. .note NAME
  269. StartPrinterDump - Send a graphics dump to the printer.
  270. .synopsis StartPrinterDump(Support,WaitUntilDone)
  271. .note FUNCTION
  272. A printer graphics dump following a call to CreatePrinterSupport is
  273. executed.
  274. .note INPUTS
  275. .info Support
  276. Pointer to a PrinterSupport-structure.
  277. .info WaitUntilDone
  278. TRUE if you want the request to be satisfied before this function
  279. returns.
  280. .note RESULTS
  281. .note BUGS
  282. .see mxm.library/CreatePrinterSupport, printer.device/PRD_DUMPRPORT
  283.  
  284. .function StopPrinterDump
  285. .note NAME
  286. StopPrinterDump - Stop a graphics dump being in progress.
  287. .synopsis Success = StopPrinterDump(Support,WaitUntilDone)
  288. .note FUNCTION
  289. A printer graphics dump started with StartPrinterDump() can be stopped
  290. with this function.
  291. .note INPUTS
  292. .info Support
  293. Pointer to a PrinterSupport-structure.
  294. .info WaitUntilDone
  295. TRUE if you want this function to return after the AbortIO function
  296. has been satisfied.
  297. .note RESULTS
  298. .info Success
  299. Boolean, FALSE if printer graphics dump was not to be aborted.
  300. .note BUGS
  301. .see mxm.library/CreatePrinterSupport,
  302. mxm.library/StartPrinterSupport, printer.device/PRD_DUMPRPORT
  303.  
  304. .function DeleteTimer
  305. .note NAME
  306. DeleteTimer - Delete a timer-request.
  307. .synopsis DeleteTimer(TimeRequest)
  308. .note FUNCTION
  309. This function deallocates a timer.device request previously allocated
  310. via CreateTimer.
  311. .note INPUTS
  312. .info TimeRequest
  313. Pointer to a timerequest structure.
  314. .note RESULTS
  315. .note BUGS
  316. .see
  317.  
  318. .function CreateTimer
  319. .note NAME
  320. CreateTimer - Create a timer-request
  321. .synopsis TimeRequest = CreateTimer(Unit)
  322. .note FUNCTION
  323. A timer-request is created with this function, depending on the
  324. requested device driver unit.
  325. .note INPUTS
  326. .info Unit
  327. The unit to be opened, can be either UNIT_VBLANK or UNIT_MICROHZ.
  328. .note RESULTS
  329. .info TimeRequest
  330. Pointer to a timerequest-structure, or NULL.
  331. .note BUGS
  332. .see
  333.  
  334. .function WaitForTimer
  335. .note NAME
  336. WaitForTimer - Wait a given period of time.
  337. .synopsis WaitForTimer(TimeRequest,TimeVal)
  338. .note FUNCTION
  339. This function gets the timer.device to wait a period of time.
  340. .note INPUTS
  341. .info TimeRequest
  342. Pointer to a timerequest-structure.
  343. .info TimeVal
  344. Pointer to a timeval-structure.
  345. .note RESULTS
  346. .note BUGS
  347. .see
  348.  
  349. .function TimeDelay
  350. .note NAME
  351. TimeDelay - Wait a given period of time.
  352. .synopsis TimeDelay(Seconds,Micros,Unit)
  353. .note FUNCTION
  354. This function gets the timer.device to wait a period of time.
  355. .note INPUTS
  356. .info Seconds
  357. Seconds to wait.
  358. .info Micros
  359. Microseconds to wait.
  360. .info Unit
  361. The unit to be opened, can be either UNIT_VBLANK or UNIT_MICROHZ.
  362. .note RESULTS
  363. .note BUGS
  364. .see
  365.  
  366. .function KeyConvert
  367. .note NAME
  368. KeyConvert - Convert a raw-key to an ANSI character.
  369. .synopsis Character = KeyConvert(IntuiMesssage)
  370. .note FUNCTION
  371. This function converts the contents of an IntuiMessage raw-key event
  372. according to the current keymap settings into a real ANSI-character.
  373. .note INPUTS
  374. .info IntuiMessage
  375. Pointer to IntuiMessage-structure.
  376. .note RESULTS
  377. .info Character
  378. ANSI character, or NULL.
  379. .note BUGS
  380. .see
  381.  
  382. .function InvertKey
  383. .note NAME
  384. InvertKey - Convert an ANSI character into an InputEvent.
  385. .synopsis Event = InvertKey(Code,Event,Command,ExtraInfo)
  386. .note FUNCTION
  387. This function turns an ANSI character into an InputEvent structure
  388. which can be used to feed it back into the stream of input events.
  389. .note INPUTS
  390. .info Code
  391. ANSI character to be converted.
  392. .info Event
  393. Pointer to InputEvent-structure.
  394. .info Command
  395. A combination of the flags IK__BUILDLIST, IK__USEIKM, IK__USELIST or
  396. IK__NOSPECIAL.
  397. .info ExtraInfo
  398. This flag should be set to zero.
  399. .note RESULTS
  400. .info Event
  401. Pointer back to input argument, or NULL.
  402. .note BUGS
  403. .see
  404.  
  405. .function EraseGadget
  406. .note NAME
  407. EraseGadget - Clear the background of a gadget.
  408. .synopsis EraseGadget(RastPort,Gadget,Colour)
  409. .note FUNCTION
  410. The imagery of gadget is erased with this function.
  411. .note INPUTS
  412. .info RastPort
  413. Pointer to the RastPort-structure the gadget will be erased from.
  414. .info Gadget
  415. Pointer to a Gadget-structure.
  416. .info Colour
  417. The pen number to erase the Gadget imagery with.
  418. .note RESULT
  419. The gadget's imagery is erased.
  420. .note BUGS
  421. .see
  422.  
  423. .function RefreshGadget
  424. .note NAME
  425. RefreshGadget - Refresh a single Gadget.
  426. .synopsis RefreshGadget(Gadget,Window)
  427. .note FUNCTION
  428. This function refreshes a single gadget, not the whole list.
  429. .note INPUTS
  430. .info Gadget
  431. Pointer to a Gadget-structure.
  432. .info Window
  433. Pointer to a Window-structure.
  434. .note RESULTS
  435. The gaget's imagery gets redrawn.
  436. .note BUGS
  437. .see
  438.  
  439. .function GetLongInt
  440. .note NAME
  441. GetLongInt - Get a value from a long integer gadget.
  442. .synopsis Value = GetLongInt(Gadget)
  443. .note FUNCTION
  444. This function returns the value currently displayed in a long integer
  445. gadget.
  446. .note INPUTS
  447. .info Gadget
  448. Pointer to a Gadget-structure.
  449. .note RESULTS
  450. .info Value
  451. The long integer value.
  452. .note BUGS
  453. .see
  454.  
  455. .function SetLongInt
  456. .note NAME
  457. SetLongInt - Set the value of a long integer gadget.
  458. .synopsis SetLongInt(Gadget,Val)
  459. .note FUNCTION
  460. This function sets the value to be displayed in a long integer gadget.
  461. .note INPUTS
  462. .info Gadget
  463. Pointer to a Gadget-structure.
  464. .info Val
  465. Long integer value to be put into the gadget.
  466. .note RESULTS
  467. .note BUGS
  468. The Gadget has to be refreshed to actually see the value displayed.
  469. .see
  470.  
  471. .function GetGadgetString
  472. .note NAME
  473. GetGadgetString - Get a string from a string gadget.
  474. .synopsis String = GetGadgetString(Gadget)
  475. .note FUNCTION
  476. This function returns a pointer to the ASCII-string buffer of a string
  477. gadget.
  478. .note INPUTS
  479. .info Gadget
  480. Pointer to a Gadget-structure.
  481. .note RESULTS
  482. .info String
  483. Pointer to an unsigned char (UBYTE).
  484. .note BUGS
  485. .see
  486.  
  487. .function SetGadgetString
  488. .note NAME
  489. SetGadgetString - Set the string for a string gadget.
  490. .synopsis SetGadgetString(Gadget,String)
  491. .note FUNCTION
  492. This function sets the string to be displayed in a string gadget.
  493. .note INPUTS
  494. .info Gadget
  495. Pointer to a Gadget-structure.
  496. .info String
  497. Pointer to an unsigned char (UBYTE), i.e. String to be set.
  498. .note RESULTS
  499. .note BUGS
  500. The Gadget has to be refreshed to actually see the string displayed.
  501. .see
  502.  
  503. .function GetToggleGadget
  504. .note NAME
  505. GetToggleGadget - Get the state of a Bool-Gadget.
  506. .synopsis State = GetToggleGadget(Gadget)
  507. .note FUNCTION
  508. This function returns the state of a Bool-Gadget which has the
  509. TOGGLEGADGET flags set and can be selected/unselected.
  510. .note INPUTS
  511. .info Gadget
  512. Pointer to a Gadget-structure.
  513. .note RESULTS
  514. .info State
  515. Boolean value, TRUE if gadget is selected, false if otherwise.
  516. .note BUGS
  517. .see
  518.  
  519. .function SetToggleGadget
  520. .note NAME
  521. SetToggleGadget - Set the state of a Bool-Gadget.
  522. .synopsis SetToggleGadget(Gadget,State)
  523. .note FUNCTION
  524. This function sets the select state of a Bool-Gadget which has the
  525. TOGGLEGADGET flags set and can be selected/unselected.
  526. .note INPUTS
  527. .info Gadget
  528. Pointer to a Gadget-structure.
  529. .info State
  530. Boolean, TRUE if gadget is to be selected, FALSE if otherwise.
  531. .note RESULTS
  532. .note BUGS
  533. The Gadget has to be refreshed to actually see the state displayed.
  534. .see
  535.  
  536. .function SetWaitPointer
  537. .note NAME
  538. SetWaitPointer - Change the pointer to a Zzz-Balloon.
  539. .synopsis SetWaitPointer(Window)
  540. .note FUNCTION
  541. This function changes the mouse pointer of a window to the standard
  542. Workbench-Balloon, indicating that the running task is busy.
  543. .note INPUTS
  544. .info Window
  545. Pointer to a Window-structure.
  546. .note RESULTS
  547. The mouse pointer gets changed.
  548. .note BUGS
  549. .see
  550.  
  551. .function PopRequest
  552. .note NAME
  553. PopRequest - Display a pop-up-requester.
  554. .synopsis Result = PopRequest(ParentWindow,TitleText,BodyText,PosText,NegText,Default,ExtraInfo)
  555. .note FUNCTION
  556. This function brings up a pop-up-requester which is automatically
  557. centered under the mouse pointer. The requester can be answered via
  558. keyboard, supported positive keys are: Y, J, V, C, R, Return; negative
  559. keys are: N, Q, B, Escape. Having answered the requester the original
  560. front screen is brought to the front again.
  561. .note INPUTS
  562. .info ParentWindow
  563. Pointer to a Window structure in which you want the requester to
  564. appear, may be NULL, so requester will appear on the Workbench screen.
  565. .info TitleText
  566. The title of the requester window, may be NULL, so "System Request:"
  567. will be used.
  568. .info BodyText
  569. The text you want to be displayed inside the requester may include
  570. ANSI-control sequences (boldface, italics, different colours, etc.)
  571. .info PosText
  572. Text for positive response Gadget, may be NULL in which case no positive
  573. Gadget will be displayed.
  574. .info NegText
  575. Tetx for negative response Gadget, may be NULL in which case no
  576. negative Gadget will be displayed. PosText & NegText being NULL,
  577. NegText will default to "Okay".
  578. .info Default
  579. Boolean value indicating the default value expected from the
  580. requester.
  581. .info ExtraInfo
  582. Pointer to a PopSupport structure.
  583. .note RESULTS
  584. .info Result
  585. Boolean, depending on the gadget being selected.
  586. .note BUGS
  587. .see mxmbase.h/struct PopSupport
  588.  
  589. .function PopMenu
  590. .note NAME
  591. PopMenu - Display a pop-up-menu.
  592. .synopsis Item = PopMenu(Menu,Window)
  593. .note FUNCTION
  594. This function displays a menu, very similar to the standard Intuition
  595. menus, just under the mouse pointer.
  596. .note INPUTS
  597. .info Menu
  598. Pointer to a Menu-structure.
  599. .info Window
  600. Pointer to a Window-structure.
  601. .note RESULTS
  602. The menu item selected, or -1 if no item was selected.
  603. .note BUGS
  604. PopMenu does not handle sub-items in the current release.
  605. .see mxmbase.h
  606.  
  607. .function Announce
  608. .note NAME
  609. Announce - Produce an audible signal.
  610. .synopsis Announce()
  611. .note FUNCTION
  612. Announce produces a sound, not a beep but a chime, on two stereo channels.
  613. .note INPUTS
  614. .note RESULTS
  615. .note BUGS
  616. .see
  617.  
  618. .function CheckSumCRC
  619. .note NAME
  620. CheckSumCRC - Calculate the 16-bit crc checksum for a memory block.
  621. .synopsis CRC = CheckSumCRC(Mem,Size)
  622. .note FUNCTION
  623. This function uses the Satchell/Forsberg-crc-function to calculate the 16-bit checksum
  624. for a memory block with given size.
  625. .note INPUTS
  626. .info Mem
  627. Pointer to memory block to be checksummed.
  628. .info Size
  629. Size of the memory block to be checksummed.
  630. .note RESULTS
  631. .info CRC
  632. The 16-bit crc value for the memory block.
  633. .note BUGS
  634. .see
  635.  
  636. .function CheckSumSimple
  637. .note NAME
  638. CheckSum - Calculate a simple checksum for a memory block.
  639. .synopsis Check = CheckSum(Mem,Size)
  640. .note FUNCTION
  641. Similar to CheckSumCRC this function calculates a checksum for a memory
  642. block with given size. The algorithm employed is simpler.
  643. .note INPUTS
  644. .info Mem
  645. Pointer to memory block to be checksummed.
  646. .info Size
  647. Size of the memory block to be checksummed.
  648. .note RESULTS
  649. .info Check
  650. The 32-bit checksum value for the memory block.
  651. .note BUGS
  652. .see mxm.library/CheckSumCRC
  653.  
  654. .function CryptBlock
  655. .note NAME
  656. CryptBlock - Encrypt/Decrypt a memory block.
  657. .synopsis CryptBlock(Mem,Size,String)
  658. .note FUNCTION
  659. This function encrypts/decrypts a block of memory using a pseudo-random
  660. number generator. The data is XOR encoded, so a double CryptBlock will
  661. result in decryption of the memory block. Additionally a string can be used
  662. as a second encryption key. The string is optional and can be left out.
  663. .note INPUTS
  664. .info Mem
  665. Pointer to memory block to be checksummed.
  666. .info Size
  667. Size of the memory block to be checksummed.
  668. .info String
  669. Pointer to second encryption string, may be null.
  670. .note RESULTS
  671. .note BUGS
  672. .see
  673.  
  674. .function IsASCII
  675. .note NAME
  676. IsASCII - Check if a character is a valid Amiga ASCII character.
  677. .synopsis IsIt = IsASCII(Character)
  678. .note FUNCTION
  679. This function checks if a character belongs to the list of valid Amiga
  680. ASCII characters.  Unlike compiler macros the international character set
  681. of the Amiga is considered.
  682. .note INPUTS
  683. .info Character
  684. The character to be checked.
  685. .note RESULTS
  686. .info IsIt
  687. Boolean, TRUE if Character is a valid Amiga ASCII character.
  688. .note BUGS
  689. .see toupper() macro
  690.  
  691. .function IsPrintable
  692. .note NAME
  693. IsPrintable - Check if a character is a printable Amiga ASCII character.
  694. .synopsis IsIt = IsPrintable(Character)
  695. .note FUNCTION
  696. This function checks if a character produces a visible result if printed.
  697. Unlike compiler macros the international character set of the Amiga is
  698. considered.
  699. .note INPUTS
  700. .info Character
  701. The character to be checked.
  702. .note RESULTS
  703. .info IsIt
  704. Boolean, TRUE if Character is a valid Amiga ASCII
  705. character.
  706. .note BUGS
  707. .see isprintable() macro
  708.  
  709. .function ToUpper
  710. .note NAME
  711. ToUpper - Change a character to upper case.
  712. .synopsis NewCharacter = ToUpper(Character)
  713. .note FUNCTION
  714. This function turns a character into an upper case character. Unlike
  715. compiler macros the international character set of the Amiga is considered.
  716. .note INPUTS
  717. .info Character
  718. The character to be turned to upper case.
  719. .note RESULTS
  720. .info NewCharacter
  721. The upper case equivalent to the input character.
  722. .note BUGS
  723. .see toupper() macro
  724.  
  725. .function UStrCmp
  726. .note NAME
  727. UStrCmp - Case insensitive strcmp().
  728. .synopsis Difference = UStrCmp(Source,Target)
  729. .note FUNCTION
  730. This function does a strcmp(), character by character, and uses the
  731. ToUpper() function to compare the characters. It also matches
  732. lower/upper case international characters.
  733. .note INPUTS
  734. .info Source
  735. Pointer to source string.
  736. .info Target
  737. Pointer to target string.
  738. .note RESULTS
  739. .info Difference
  740. The Difference between the strings to be compared, 0 if no difference.
  741. .note BUGS
  742. .see mxm.library/ToUpper()
  743.  
  744. .function Random
  745. .note NAME
  746. Random - Generate a random value.
  747. .synopsis Value = Random(MaxValue)
  748. .note FUNCTION
  749. Random returns a random value between 0 and MaxValue - 1. The random
  750. seed is XORed with the current video beam position, so the random
  751. value is guaranteed not to produce repeated sequences of pseudo-random
  752. values.
  753. .note INPUTS
  754. .info MaxValue
  755. The maximum value + 1 expected from this function.
  756. .note RESULTS
  757. .info Value
  758. Random value.
  759. .note BUGS
  760. .see
  761.  
  762. .function FindFileWindow
  763. .note NAME
  764. FindFileWindow - Find the window associated with a FileHandle.
  765. .synopsis Window = FindFileWindow(Handle)
  766. .note FUNCTION
  767. This function finds the Intuition window associated with a Console
  768. FileHandle by passing the handler task a a request to identify its
  769. volume node (i.e.: the Window).
  770. .note INPUTS
  771. .info Handle
  772. BPTR to a FileHandle-structure.
  773. .note RESULTS
  774. .info Window
  775. Pointer to a Window-structure.
  776. .note BUGS
  777. This function will produce garbage if used on non-console FileHandles.
  778. .see
  779.  
  780. .function DeleteHiddenRPort
  781. .note NAME
  782. DeleteHiddenRPort - Delete a hidden RastPort created by
  783. CreateHiddenRPort().
  784. .synopsis Pointer = DeleteHiddenRPort(RastPort)
  785. .note FUNCTION
  786. This function deallocates a hidden RastPort previously created with
  787. CreateHiddenRPort().
  788. .note INPUTS
  789. .info RastPort
  790. Pointer to a RastPort-structure.
  791. .note RESULTS
  792. This function always returns NULL, so user can do Pointer =
  793. DeleteHiddenRPort(Pointer).
  794. .note BUGS
  795. .see
  796.  
  797. .function CreateHiddenRPort
  798. .note NAME
  799. CreateHiddenRPort - Create a hidden RastPort.
  800. .synopsis RastPort = CreateHiddenRPort(Width,Height,Depth)
  801. .note FUNCTION
  802. This function allocates a RastPort structure, a BitMap structure,
  803. initializes them and adds the requested number of planes to the
  804. BitMap. The planes are zeroed out before this function returns.
  805. .note INPUTS
  806. .info Width
  807. Width of the RastPort.
  808. .info Height
  809. Height of the RastPort.
  810. .info Depth
  811. Depth of the RastPort.
  812. .note RESULTS
  813. .info RastPort
  814. Pointer to a RastPort structure, or NULL.
  815. .note BUGS
  816. .see
  817.  
  818. .function EnableWindow
  819. .note NAME
  820. EnableWindow - Enable all gadgets of a window and restore the mouse
  821. pointer.
  822. .synopsis EnableWindow(Window)
  823. .note FUNCTION
  824. This function reenables the gadgets of a window previously disabled
  825. with DisableWindow() and sets the standard system mouse pointer.
  826. .note INPUTS
  827. .info Window
  828. The Window to be reenabled.
  829. .note RESULTS
  830. .note BUGS
  831. Can only handle windows really disabled via DisableWindow(), may crash
  832. on other windows.
  833. .see mxm.library/DisableWindow()
  834.  
  835. .function DisableWindow
  836. .note NAME
  837. DisableWindow - Disable all gadgets of a window and set a Zzz mouse
  838. pointer.
  839. .synopsis Success = DisableWindow(Window)
  840. .note FUNCTION
  841. This function disables all custom gadgets to be found in the window
  842. and sets a Zzz mouse pointer.
  843. .note INPUTS
  844. .info Window
  845. Pointer to a Window-structure.
  846. .note RESULTS
  847. .info Success
  848. Boolean, TRUE if window was disabled.
  849. .note BUGS
  850. You MUST not remove or add Gadgets to the window after it has been
  851. disabled, or EnableWindow() will panic.
  852. .see mxm.library/EnableWindow()
  853.